Get FX Quote

Get a quote for a specific foreign exchange conversion need. The API operates in two modes:

• FIRM — Merchant provides a specific amount → Baokim returns quote_id with expiry time (expires_at), exchange rate committed for that amount. Used for execution at Create Conversion.
• INDICATIVE — Merchant does not provide amount → Baokim returns reference exchange rate for display, without executable quote_id. To convert, must call again with FIRM type

Workflow

Endpoint

• URL: /api/v1/fx/quote
• Method: POST

Request

Parameter	Data Type	Required	Description
request_id	string(50)	Yes	See section 3 Introduction
request_time	string(19)	Yes	See section 3 Introduction
merchant_code	string(20)	Yes	See section 3 Introduction
trade_type	string(4)	Yes	Transaction type from Merchant's perspective: SELL (Merchant sells foreign currency, receives VND) or BUY (Merchant uses VND to buy foreign currency)
from_currency	string(3)	Yes	Currency Merchant currently holds (source currency), e.g., USD
to_currency	string(3)	Yes	Currency Merchant wants to receive (destination currency), e.g., VND
amount	decimal(18,2)	No	Intended conversion amount, must be > 0. If provided → FIRM quote (with quote_id, executable). If not provided → INDICATIVE quote (reference only, no quote_id).
fixed_side	string(4)	No	Fixed side of the amount, only meaningful when amount is provided. FROM (default): amount is the source amount Merchant wants to sell, system calculates the amount received. TO: amount is the destination amount Merchant needs to receive, system calculates the source amount needed.

Validation Rules

• Exactly one of from_currency/to_currency must be VND; violation → code 422
• trade_type must match direction: SELL ⇔ from_currency is foreign currency, to_currency is VND; BUY ⇔ from_currency is VND, to_currency is foreign currency. Mismatch → code 422
• Supported foreign currency: must be in the merchant's configured list; outside list → code 404
• amount: if provided, must be > 0; when fixed_side is on VND side, amount must be integer; violation → code 422
• fixed_side without amount: system ignores fixed_side, returns INDICATIVE quote

Example Request — FIRM (Merchant has 10,000 USD, wants to sell for VND)

{
  "request_id": "MERCHANT1234BK202606050001",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "trade_type": "SELL",
  "from_currency": "USD",
  "to_currency": "VND",
  "amount": 10000.00,
  "fixed_side": "FROM"
}

Example Request — INDICATIVE (reference rate only)

{
  "request_id": "MERCHANT1234BK202606050005",
  "request_time": "2026-06-05 10:15:30",
  "merchant_code": "MERCHANT1234",
  "trade_type": "BUY",
  "from_currency": "VND",
  "to_currency": "USD"
}

Response

Parameter	Data Type	Required	Description
response_code	int(4)	Yes	Result code
response_message	string(200)	Yes	Description of the result code
merchant_code	string(20)	Yes	Merchant code
data	Object	Yes	Quote details (see table below)

data Structure

Parameter	Data Type	Description
quote_type	string(10)	Quote type: FIRM or INDICATIVE
quote_id	string(50)	Quote code used for execution at Create Conversion. Null when quote_type = INDICATIVE.
trade_type	string(4)	Transaction type, echoed from request
currency_pair	string(10)	Normalized currency pair, always in format FOREIGN_CURRENCY/VND (e.g., USD/VND), regardless of transaction direction
rate	decimal(18,4)	Applicable exchange rate, expressed per currency_pair: 1 unit of foreign currency = rate VND. For FIRM: rate already applied for the requested amount. For INDICATIVE: reference rate.
from_currency	string(3)	Source currency
from_amount	decimal(18,2)	Source amount. If fixed_side = TO, this is system-calculated. Null when quote_type = INDICATIVE.
to_currency	string(3)	Destination currency
to_amount	decimal(18,2)	Destination amount Merchant will receive. If fixed_side = FROM, this is system-calculated. Null when quote_type = INDICATIVE.
fee_amount	decimal(18,2)	Conversion fee (currently: 0, fee already included in exchange rate)
fee_currency	string(3)	Currency of the fee
quoted_at	string(19)	Time quote was generated (GMT+7), format YYYY-MM-DD HH:MM:SS
expires_at	string(19)	Quote expiry time. After this time, quote_id cannot be executed. Default TTL: x minutes. Null when quote_type = INDICATIVE.

Example Response — FIRM

{
  "response_code": 200,
  "response_message": "Success",
  "merchant_code": "MERCHANT1234",
  "data": {
    "quote_type": "FIRM",
    "quote_id": "FXQ0605A7K2M9XD41",
    "trade_type": "SELL",
    "currency_pair": "USD/VND",
    "rate": 26450.0000,
    "from_currency": "USD",
    "from_amount": 10000.00,
    "to_currency": "VND",
    "to_amount": 264500000,
    "fee_amount": 0,
    "fee_currency": "VND",
    "quoted_at": "2026-06-05 10:15:30",
    "expires_at": "2026-06-05 10:25:30"
  }
}

Example Response — INDICATIVE

{
  "response_code": 200,
  "response_message": "Success",
  "merchant_code": "MERCHANT1234",
  "data": {
    "quote_type": "INDICATIVE",
    "quote_id": null,
    "trade_type": "BUY",
    "currency_pair": "USD/VND",
    "rate": 26430.0000,
    "from_currency": "VND",
    "from_amount": null,
    "to_currency": "USD",
    "to_amount": null,
    "fee_amount": 0,
    "fee_currency": "VND",
    "quoted_at": "2026-06-05 10:15:30",
    "expires_at": null
  }
}

Error Codes

Response Code	Response Message	Description
200	Success
101	System error	Unexpected error on Baokim's side
110	Invalid merchant code	merchant_code is undefined or not allowed
120	Invalid Signature	Signature header is invalid
404	Currency not supported	Requested foreign currency is not in Merchant's list
422	Validation error	Request field validation failed (wrong transaction direction, no VND, invalid amount…)
423	FX rate temporarily unavailable	No reliable rate available at this moment
429	Too many requests	Exceeded rate limit for Merchant